with v8.Class_Handle, v8.Class_Handle.Class_Local, v8.Class_Handle.Class_Persistent;
generic
   type Pointer is private;
package v8.Generic_Handles is
   package Class_Handle is new v8.Class_Handle (Pointer);

   package Class_Local is new Class_Handle.Class_Local;

   package Class_Persistent is new Class_Handle.Class_Persistent;

   subtype Handle is Class_Handle.Handle;
   -- An object reference managed by the v8 garbage collector.
   --
   -- All objects returned from v8 have to be tracked by the garbage
   -- collector so that it knows that the objects are still alive.  Also,
   -- because the garbage collector may move objects, it is unsafe to
   -- point directly to an object.  Instead, all objects are stored in
   -- handles which are known by the garbage collector and updated
   -- whenever an object moves.  Handles should always be passed by value
   -- (except in cases like out-parameters) and they should never be
   -- allocated on the heap.
   --
   -- There are two types of handles: local and persistent handles.
   -- Local handles are light-weight and transient and typically used in
   -- local operations.  They are managed by HandleScopes.  Persistent
   -- handles can be used when storing objects across several independent
   -- operations and have to be explicitly deallocated when they're no
   -- longer used.
   --
   -- It is safe to extract the object stored in the handle by
   -- dereferencing the handle (for instance, to extract the Object-- from
   -- a Handle<Object>); the value will still be governed by a handle
   -- behind the scenes and the same rules apply to these values as to
   -- their handles.

   subtype Local is Class_Local.Local;
   -- A light-weight stack-allocated object handle.  All operations
   -- that return objects from within v8 return them in local handles.  They
   -- are created within HandleScopes, and all local handles allocated within a
   -- handle scope are destroyed when the handle scope is destroyed.  Hence it
   -- is not necessary to explicitly deallocate local handles.

   subtype Persistent is Class_Persistent.Persistent;
   -- An object reference that is independent of any handle scope.  Where
   -- a Local handle only lives as long as the HandleScope in which it was
   -- allocated, a Persistent handle remains valid until it is explicitly
   -- disposed.
   --
   -- A persistent handle contains a reference to a storage cell within
   -- the v8 engine which holds an object value and which is updated by
   -- the garbage collector whenever the object is moved.  A new storage
   -- cell can be created using Persistent :  : New and existing handles can
   -- be disposed using Persistent :  : Dispose.  Since persistent handles
   -- are passed by value you may have many persistent handle objects
   -- that point to the same storage cell.  For instance, if you pass a
   -- persistent handle as an argument to a function you will not get two
   -- different storage cells but rather two references to the same
   -- storage cell

end v8.Generic_Handles;
